Release 10.1A: OpenEdge Development:
Programming Interfaces

Reading data on a socket

To read data from a connected TCP/IP socket, you invoke the READ( ) method on the corresponding socket object (SELF:READ( ) within the corresponding READ-RESPONSE event procedure). You can invoke this method on a connected socket at any time to read data. However, the method blocks depending on the amount of data available on the socket, the reading mode that you use, and the timeout value (set by the SO-RCVTIMEO option of the SET-SOCKET-OPTION() method).

The syntax of the READ( ) method follows:

Syntax

READ( memptr-expression , position , bytes-to-read [ , mode ] )

The READ( ) method transfers data from the socket to the specified MEMPTR variable, memptr-expression, at the byte position in the MEMPTR region specified by the INTEGER expression, position. Exactly how much data the READ( ) method blocks to read depends on:

The number of bytes specified by the INTEGER bytes-to-read.
The reading mode specified by the INTEGER mode.
The timeout value, set by the SO-RCVTIMEO option of the SET-SOCKET-OPTION() method.

Specifying the read mode

You can specify mode using a compiler constant as shown in Table 17–3.

Table 17–3: Socket reading modes 

Compiler constant	Value	Description
READ-AVAILABLE	1	The READ( ) method blocks until at least one (1) byte is available on the socket and reads the number of bytes that are available up to a maximum of bytes-to-read bytes.
READ-EXACT-NUM	2	(Default) The READ( ) method blocks until bytes-to-read bytes are available to read from the socket.

Thus, you can have the READ( ) method block until exactly the specified number of bytes are read (the default), or until all available bytes are read up to a maximum number allowed.

The appropriate reading mode to use depends on your application requirements. Note, however, that if you specify READ-EXACT-NUM, the READ( ) method blocks until it reads the specified number of bytes (no matter how long it takes) or until the socket is disconnected (whatever happens first).

Specifying the timeout length

Besides setting the read mode, you can also set the amount of time READ() waits before timing out. To do so, use the SO-RCVTIMEO option of the SET-SOCKET-OPTION() method. If you do not set a timeout value, the default is for READ() to wait forever.

READ()’s timeout behavior is affected by the interaction of the read mode and the timeout value, as Table 17–4 illustrates.

Table 17–4: Effect of read mode and timeout value on READ()’s
timeout behavior

Read mode	With a timeout value	Without a timeout value
READ-AVAILABLE	Assuming there are no connection failures, READ() blocks until one for the following occurs: The timeout expires. There is at least one byte available to read on the socket.	Assuming there are no connection failures, READ() blocks until there is at least one byte available to read on the socket.
READ-EXACT-NUM	Assuming there are no connection failures: If there is any data on the socket, READ() blocks until there are bytes-to-read bytes available to read on the socket. Else, READ() blocks until the timeout expires.	Assuming there are no connection failures, READ() blocks until there are bytes-to-read bytes available to read on the socket.

Verifying the number of bytes actually read

You can verify the number of bytes actually read by the READ( ) method. The number of bytes read by the last READ( ) method invoked on a socket object is equal to the value of the BYTES-READ attribute invoked on the same socket object.